Remote control your OLAP server

There is an almost unknown tool within every instantOLAP installation, the instantOLAP Console, which allows to remote-control your instantOLAP server and to start, stop or rebuild models, to rebuild single dimensions or cubes or to perform a number of other operations.

The tool is very useful whenever instantOLAP loads its data from a data-warehouse and you want to rebuild certain models, dimensions or cubes after the ETL tool rebuild the warehouse or added new data to it.

This article describes, how to use the tool from batch-files or other Java applications (most ETL tools can call native Java commands) and which operations are available.

[toc]

The console is delivered as a simple Java archive (jar file) and is located in the folder <instantOLAP>/tools/console. You can use the archive from this location or copy it to another computer – no other resource (except a local Java installation) is needed to execute the application.

Starting the console (interactive mode)

To start the console in the interactive mode, use the command:

java -jar iolapConsole.jar <server-url> <user> <password>

where <server-url> is the complete url to the backend-service of your instantOLAP-server and <user> and <password> are the credentials for your administrator account. E.g. the command for a local installation on port 8080 and with the administrator account would be:

java -jar iolapConsole.jar http://localhost:8080/iolapWS admin admin

If the jar file is not located in the current folder, you can also type its whole path (relative or absolute). After you logged successfully into the server, you will see the following welcome message:

instantOLAP console
(c) 2006-2009 Thomas Behrends Softwareentwicklung e.K.
Connecting server http://localhost:8080/iolapWS...
ok
>

Now you can use one of following commands to control the server:

Commands

BUILDDIMENSION <model> <dimension>

This command rebuilds a single dimension of a model (and all dimensions being dependend on this). The command expects the model name and dimension name as argument.

Example:

> BUILDDIMENSION demo/demo Product
Building dimension Product of model demo/demo...

BUILDDIMENSIONS <model>

This command rebuilds all dimensions of the specified model. The only argument the command expects is the name of the model.

Example:

> BUILDDIMENSIONS demo/demo
Building dimensions of model demo/demo...

BUILDSTORE <model> <store>

The command BUILDSTORE rebuilds a single store of the specified model, the store name has to be passed as second argument.

Example:

> BUILDSTORE demo/demo store1
Building store store1 of model demo/demo...

BUILDSTORES <model>

Rebuilds all stores of the specified model.

Example:

> BUILDSTORES demo/demo
Building stores of model demo/demo...

CLEARCACHE <cache>

Use the command CLEARCACHE to empty a single cache of the model. After the execution, the cache still exists but contains no entries.

Example:

> CLEARCACHE demo/demo cache1
Clearing cache cache1 of model demo/demo...

CLEARCACHES

This command clear all caches of the specified model.

Example:

> CLEARCACHES demo/demo
Clearing caches of model demo/demo...

CLEARSTORE <model> <store>

Clears a single store of the model and brings it into the „offline“ state. Dependend on the configuration settings, the model will continue using the original adhoc version of the store, otherwise the system will immediatley start to rebuild the store again.

Example:

> CLEARSTORE demo/demo store1
Clearing store store1 of model demo/demo...

CLEARSTORES <model>

This command clears all stores of the model. Like in the CLEARSTORE command, the system will immediatley rebuild all stores dependend on the configuration settings.

Example:

> CLEARSTORES demo/demo
Clearing stores of model demo/demo...

LISTDIMENSIONS <model>

This command returns a list of all dimensions of the specified model.

Example:

> LISTDIMENSIONS demo/demo
Agency
Anim
Campaigns
Manufacturer
Product
Time

LISTMODELS

Returns a list of all models on your server, including the active and inactive ones. For each model, the current state is append as text. The following states are possible:

• ONLINE: The model is started and ready
• BUILD: The model is currently starting
• CLOSED: The model is currently not started
• CLOSING: The model is currently shutting down
• SYNC: The model is started and currently synchronizing its dimensions and / or cubes
• ERROR: The model is not started because an error ocurred while starting it

Example:

> LISTMODELS
demo/demo (ONLINE)
eventlog/eventlog (ONLINE)

MODELSTATE <model>

This function returns the state of a specific model. The state is returned as number in this functions, the following states are possible:

• 0 = CLOSED
• 1 = BUILD
• 2 = ONLINE
• 3 = SYNC
• 4 = ERROR
• 5 = CLOSING

Example:

> MODELSTATE demo/demo
Request model-state for demo/demo...
State = 2

QUIT

This command stops the console.

STARTSYNC <model> <timeout>

This function starts the synchronize process for a model, in which it is checking its cubes and dimensions if they are outaged. You must pass the timeout for the synchronize process in ms as second argument. This function is only useful if you want to synchronize the model immediatly, because the system synchronizes all its online models each minute.

Example:

> STARTSYNC demo/demo 1000
Starting model demo/demo synchronize...

START <model>

This command starts the specified model.

Example:

>START demo/demo
Starting model demo/demo asynchron...

STOP <model>

This command shuts down the specified model.
Example:

> STOP demo/demo
Stopping model demo/demo...
ok

WAIT <seconds>

This command simply waits the given number of seconds.

Using the console in batch mode

The batch mode can be used to call the console from external batch files and to execute commands without user interaction. To execute a command, just add it and its arguments behind the standard arguments of the console, the syntax for the batch mode is:

java -jar iolapConsole.jar <server> <user> <pwd> <command> [<arg1> [<arg2> [...] ] ]

If you call the console in batch mode, it will immediatley execute the passed command and then exit. E.g. the following line

java -jar iolapConsole.jar http://localost:8080/iolapWS admin admin START demo/demo

would start the model „demo/demo“ on a local server running on port 8080 and then return.

Note that all commands except STARTSYNC, also in the interactive mode, only fork the requested operation on the server and then return without waiting for the operation to be finished. However, if you send a number of commands for the same model to server, they will be queued and executed in sequential order.